<?php
/**
 * Interfaces
 *
 * @todo implement iterator http://fr.php.net/manual/fr/language.oop5.iterations.php
 * @link http://webappkit.net
 * @package webappkit
 * @subpackage db
 * @author J.Ducastel <nospam0@ducastel.name>
 * @license http://opensource.org/licenses/gpl-license.php GNU Public License
 */

/**
 * please note that iCollection implementations have to implements also iterator
 */
interface iCollection extends Iterator {

    /**
     * Filters current selection on a key/value pair
     *
     * @param  string $key
     * @param  mixed $value
     * @return bool True if the filter is applied on selection
     */
    public function filter($key, $value);

    /**
     * Applies a list of filters, grouped in associative array, to the selection
     *
     * @param array $filters
     * @return bool True if all filters have been applied
     */
    public function filters($filters);

    /**
     * Count items belonging to the current selection
     *
     * @return int
     */
    public function count();

    /**
     * Return items belonging to the current selection
     *
     * @return array
     */
    public function getList();

    /**
     * Removes all of the currently selected items
     *
     * @return bool
     */
    public function deleteAll();

    /**
     * Get an item, either the first in selection or by primary key
     *
     * @param  mixed $key primary key value.
     * if null, will return the first item in selection
     * @return object
     */
    public function get($key=null);

    /**
     * Insert an object into the collection
     *
     * Updates object if necessary (set auto-incremented key, etc)
     *
     * @param  object $item
     * @return bool
     */
    public function insert(&$item);

    /**
     * Update an object within the collection
     *
     * Updates object if necessary (set auto-incremented key, etc)
     *
     * @param  object $item
     * @return bool
     */
    public function update(&$item);

    /**
     * Remove an object from the collection
     *
     * @param  object $item
     * @return bool
     */
    public function remove($item);

}

/**
 * Please note that iDbCollection implementations have to implements also iterator
 */
interface iDbCollection extends iCollection {

    /**
     * @param DbLinkTool $link
     */
    public function __construct(&$link);

    /**
     * Return an extract (page) of the current selected items
     *
     * @param  int $index page index, leading 1
     * @param  int $lines lines per page, default is 20
     * @return array
     */
    public function getPage($index=1, $lines=20);

    /**
     * Return pages cout having $lines items per page
     *
     * @param  int $lines lines per page, default is 20
     * @return int
     */
    public function countPages($lines=20);
}

interface iDbCollectionItem {

    /**
     * Sets object's database id
     *
     * @param  mixed $id
     * @return bool
     */
    function setId($id);
}